Update --base-url recipe docs, and add warning box#138
Update --base-url recipe docs, and add warning box#138mre merged 3 commits intolycheeverse:masterfrom
Conversation
The goal is to add more detail where I can, and to remove information which I think is no longer correct. I think this page was originally written when --base-url behaved quite differently (before --root-dir?). I've left all of the examples even though I think they will not work. The examples are all very brief so I don't know what they're intended to show. I've left them to be safe. The statements which I've removed or changed because I think they're no longer correct are: > Even though your site isn't deployed yet, lychee can verify that the > files your links point to exist in your project. > The `--base-url` parameter works similarly to other tools you might know: > --base-url: Use it when you care about your site's final URL structure
|
|
||
| - You're only checking fully-qualified URLs. | ||
| - Your site runs at a root domain like `example.com`. | ||
| - Your relative links should resolve to other local files based on their folder structure. |
There was a problem hiding this comment.
The "other" suggests that we check a file in the first place. It could be an online URL, though, so it's slightly confusing.
| - Your relative links should resolve to other local files based on their folder structure. | |
| - Your relative links should resolve to local files based on your folder structure. |
| [--root-dir](/recipes/root-dir/) may be useful instead. Setting a root | ||
| directory can help to resolve absolute links, and relative links will be | ||
| resolved based on a local file's path. |
There was a problem hiding this comment.
That bit about resolving absolute links is also a bit confusing.
I think we need to be super clear with our wording here as I already caused too much trouble by being imprecise in the past. 😉
Unfortunately, I don't know how to phrase it better.
| [--root-dir](/recipes/root-dir/) may be useful instead. Setting a root | |
| directory can help to resolve absolute links, and relative links will be | |
| resolved based on a local file's path. | |
| [--root-dir](/recipes/root-dir/) may be useful instead. If you set a root | |
| directory, absolute links will be resolved (what should we put here?), and relative links will be | |
| resolved based on a local file's path relative to the root directory. |
There was a problem hiding this comment.
choosing to leave this for now
| lychee --base-url https://example.com/docs/ --root-dir $(pwd)/public/ "public/**/*.html" | ||
| ``` | ||
| - [`--root-dir`](/recipes/root-dir) requires a local folder path (like `./public/`), and it: | ||
| - Applies to links with absolute paths (links beginning with `/`) in local files. |
There was a problem hiding this comment.
| - Applies to links with absolute paths (links beginning with `/`) in local files. | |
| - Only applies to links with absolute paths (e.g. links beginning with `/` on Unix or `C:\` on Windows) in local files. |
There was a problem hiding this comment.
this is using the URL notion of absolute links, so it's those beginning with /. I should avoid the word "path" to avoid confusion.
| ``` | ||
| - [`--root-dir`](/recipes/root-dir) requires a local folder path (like `./public/`), and it: | ||
| - Applies to links with absolute paths (links beginning with `/`) in local files. | ||
| - Resolves absolute links to files within the given root directory. |
There was a problem hiding this comment.
Since this can be a bit counterintuitive ("why doesn't it just check /foo and instead prefixes it with a 'root directory'?"), maybe we should add an example here.
| - Resolves absolute links to files within the given root directory. | |
| - Resolves absolute links to files within the given root directory. | |
| For example, if lychee finds a link to `/contact` in your input and the root directory is set to `/usr/lychee/site`, then it will check `/usr/lychee/site/contact`. |
There was a problem hiding this comment.
choosing to leave this for now. I also think root-dir has enough examples on the root dir page, which is linked.
|
Apart from some minor changes (see the comments), I don't see any blockers for merging this. But I'd be fine to merge it as-is as well. @katrinafyi, let me know your preference. 😉 |
|
I did mean to address the comments and I'd still like to. It's just been low priority because it's documenting something which i think is a bit broken. |
|
Ah yeah, all good. And yes, it's quite broken indeed. 😅 Somehow I wish I never introduced |
|
Merging this would be an improvement in my book. Shall we just do that? @katrinafyi, wdyt? |
|
Yeah I agree. I'll try to remember to fix the more pressing comments in a follow up PR. Sorry for the delay :) |
Co-authored-by: Matthias Endler <matthias@endler.dev>
katrinafyi
left a comment
katrinafyi
left a comment
There was a problem hiding this comment.
I've made some changes and commented on the outstanding review comments
| [--root-dir](/recipes/root-dir/) may be useful instead. Setting a root | ||
| directory can help to resolve absolute links, and relative links will be | ||
| resolved based on a local file's path. |
There was a problem hiding this comment.
choosing to leave this for now
| ``` | ||
| - [`--root-dir`](/recipes/root-dir) requires a local folder path (like `./public/`), and it: | ||
| - Applies to links with absolute paths (links beginning with `/`) in local files. | ||
| - Resolves absolute links to files within the given root directory. |
There was a problem hiding this comment.
choosing to leave this for now. I also think root-dir has enough examples on the root dir page, which is linked.
|
Thanks for working on this. Another step towards saner documentation for those options. Keep it up! ✌️ |
2 participants
The goal is to add more detail where I can, and to remove information which I think is no longer correct. I think this page was originally written when --base-url behaved quite differently (before --root-dir?).
I've left all of the examples even though I think they will not work. The examples are all very brief so I don't know what they're intended to show. I've left them to be safe.
The statements which I've removed or changed because I think they're no longer correct are:
Also don't recommend using both --root-dir and --base-url.